/*
 * Copyright 2009 Jesse McLaughlin (nzjess@gmail.com)
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *         http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.travelfusion.xmlclient.transport;

import java.io.IOException;
import java.io.InputStream;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import org.travelfusion.xmlclient.xobject.XRequest;

/**
 * This interfaces represents the underlying transport across which TRAVELfusion TripPlannerXML requests and responses
 * transit in raw XML form. Requests are passed to the transport in {@link String} form, and the responses are returned
 * in the form of an {@link InputStream}.
 * 
 * @author Jesse McLaughlin (nzjess@gmail.com)
 */
public interface TfXTransport {

  /**
   * Subclass should annotate their implementation of {@link TfXTransport#send(XRequest, String)} with this annotation,
   * to support Guice interceptor bindings.
   */
  @Target(ElementType.METHOD)
  @Retention(RetentionPolicy.RUNTIME)
  public static @interface Send {}

  /**
   * Sends the XML request and returns the corresponding response.
   * 
   * @param request the original {@link XRequest} object
   * @param requestString The raw XML request to send, as a {@link String}.
   * @return An {@link InputStream} from which the response can be read.
   * 
   * @throws IOException If something goes wrong sending the request or receiving the response.
   */
  InputStream send(XRequest request, String requestString) throws IOException;
}
